OpenEuphoria

@[:cmdline:build_commandline|]
==== build_commandline
<eucode>
include cmdline.e
default namespace is cmdline
public function build_commandline(sequence cmds)
</eucode>

Returns a text string based on the set of supplied strings.

===== Parameters:
# ##cmds## : A sequence. Contains zero or more strings.

===== Returns:
A **sequence**, which is a text string. Each of the strings in ##cmds## is
quoted if they contain spaces, and then concatenated to form a single
string.

===== Comments:
Typically, this
is used to ensure that arguments on a command line are properly formed
before submitting it to the shell.

Though this function does the quoting for you it is not going to protect
your programs from globing ##*##, ##?## . And it is not specied here what happens if you
pass redirection or piping characters.

When passing a result from with build_commandline to [[:system_exec]],
file arguments will benefit from using [[:canonical_path]] with the [[:TO_SHORT]].
On //Windows// this is required for file arguments to always work. There is a complication
with files that contain spaces. On //Unix//
this call will also return a useable filename.

Alternatively, you can leave out calls to [[:canonical_path]] and use [[:system]] instead.

===== Example 1:
<eucode>
include std/cmdline.e
include std/filesys.e -- for required canonical_path function
include std/console.e -- for display function

object s = build_commandline({"-d", canonical_path("/usr/my docs/",,TO_SHORT)})
display(s)

</eucode>

===== Result:
{{{
-d "/usr/my docs/"
}}}

===== Example 2:
You can use this to run things that might be difficult to quote out.
Suppose you want to run a program that requires quotes on its
command line? Use this function to pass quotation marks~:

<eucode>
include std/cmdline.e
include std/filesys.e -- for required canonical_path function
include std/console.e -- for display function

object s = build_commandline({"grep","-n","Hello World","*.ex"})
display(s)
object s = build_commandline({"grep","Hello World","*.ex"})
display(s)
system(s,0)
</eucode>

===== Results:
{{{
grep "Hello World" *.ex
hello.ex:3:puts(1,"Hello World!\n")
...
}}}

===== Comments:
Typically, this
is used to ensure that arguments on a command line are properly formed
before submitting it to the shell.

Though this function does the quoting for you it is not going to protect
your programs from globing ##*##, ##?## . And it is not specified here what happens if you
pass redirection or piping characters.

When passing a result from with build_commandline to [[:system_exec]],
file arguments will benefit from using [[:canonical_path]] with the [[:TO_SHORT]].
On //Windows// this is required for file arguments to always work. There is a complication
with files that contain spaces. On //Unix//
this call will also return a useable filename.

Alternatively, you can leave out calls to [[:canonical_path]] and use [[:system]] instead.

===== See Also:
[[:parse_commandline]], [[:system]], [[:system_exec]], [[:command_line]],
[[:canonical_path]], [[:TO_SHORT]]